This is a text-only version of the doc for people who do not have software which can read Microsoft Word 3.0x files. The screen shots have been deleted since graphics cannot be carried in a text-only file. You can see them by following along in the actual program instead.
Legal Notice.
This program, its algorithms, displays and documentation are hereby:
Permission is granted to distribute this program to other potential users for free so long as it is distributed with this documentation and both are distributed unchanged. This includes posting on bulletin boards and official non-profit Mac user group shareware libraries.
You specifically may not distribute this program for a charge. You may not distribute this program as part of any "shareware disk" or software collection of any kind for which there is a fee charged without written permission from the author. You may not distribute this program as an incentive to purchase other software, hardware, or any other item.
Terms.
This is a shareware program. This means that you are free to try it for a reasonable period of time to see if you find it useful and worth the modest shareware fee ($25 in this case). If you decide that you do not want to send me the fee, please delete the program from your disk. If, on the other hand, you like the program and want to continue to use it, please send $25 (US) to:
George Touchstone
29 Sacramento St.
Cambridge, Mass.
02138
This shareware fee will register you as a user of Newer and will entitle you to a disk containing the latest version of the program and documentation (or the next upgrade if you have the latest version) as well as the right to future basic upgrades and bug fixes for the price of a floppy disk and postage and handling. Please include the version number of the copy you have when registering. See also the site license terms at the end of this document.
System Requirements.
Newer was developed on, and is used almost every day on, a Mac II and IIcx running system software 6.0.5 and 6.0.7 with 8 mb of memory and a hard disk. It has also been used on a 512E running System 4.1 / Finder 5.5 (circa April 87) and on a IIci running 6.0.5. It requires the 128K (Mac Plus) or later ROM and HFS (800K) disks. It will not work very gracefully with MFS (400K) disks, either as the source or destination for the copies.
7.0 Compatibility.
The basic features of Newer have been successfully tested on system 7.0 beta of Oct 90. However, Newer uses the Symantec Capps text handing package which is known to be 32 bit unclean. It will thus not work on system 7.0 in 32 bit mode. A version which avoids this problem will be released some time in early 1991 depending on the release and acceptance of 7.0.
Overview.
Newer is basically a backup and restore program. It copies files and folders from a folder on your working disk to an external disk or from the external disk back to your working disk. It preserves full folder structure on the backup external disk, ie: the files on the copy disk are accessible by the finder and will be found in the same folders they are in on the original disk. If a copy of the file already exists, it will be copied over only if the file being copied is newer than the copy to be overwritten. This program will never copy an older version of a file onto a newer version.
Newer performs a function similar to dragging a folder or set of folders from your desktop to a floppy disk. It differs from the finder in performing this action in the following ways: 1) you can restrict the copy process to include only those files changed since a date specified by you, 2) you can specify files not to be copied either by a list of file names or by a list of file "types" (or both), 3) if a copy of a file already exists, it will not be copied over if it is already up to date, 4) rather than having to select the group of folders to be copied each time, you store the selection (and other options) in a command file which can be run again later, and 5) a log of the files copied is kept.
Features.
Newer was designed and written with the following objectives:
Minimize copying time and space on backup disks.
Provide for incremental backups.
Allow a specific selection of folders to be backed up.
Allow program options to be stored in a command file for repeated execution.
Keep a log of files copied.
Provide an update process for transporting new work between systems.
Provide a merge process for integrating work with a master system.
Copies are made to or from the folder containing the command file you use to start the program (referred to as the "command folder") and an external disk. If the command file is on the desktop of your disk, the entire disk is copied. The external disk used is the first one whose name starts with "Backup" (or a string you specify). The documentation below refers to the external disk as a "floppy disk", as it typically might be, but it could also be any device or volume which appears to be a mounted disk to the system. Examples would include: external SCSI disks (such as removeable cartridges) and foreign file systems mounted via a network such as TOPS. The only requirement is that it support HFS and have "backup" (or a string you specify) as the first characters of its name. (Note that the Macintosh file system is not upper/lower case sensitive, so that "backup" is equivalent to "Backup" or to "bAcKuP": any of these is recognized).
You provide a "timestamp" which can be a date and time you type in, the last modified time of the command file itself (ie: the last time you ran this command file) or the last modified time of another file in the command folder. Only files modified since this time are considered for copying. Of course, you can also specify a date which precedes all your work to ensure that all files not otherwise excluded are copied.
Provision is made to exclude files and/or folders from consideration. You may wish to specify a list of sub-folders of the command folder to be omitted from the copy process or you may wish that only sub-folders that you specify are copied. Additionally, you can specify individual files and/or file "types" which should be skipped.
Besides its obvious application as a backup and restore program, Newer is also useful for taking a changing set of files (eg: program sources in the process of software development or a number of files which comprise a large report) back and forth from work to home or from one machine to another. You can "backup" those files which have changed since a time known when the two systems were in sync and then "restore" on the other system to bring them back in sync. The timestamp can then be updated so that any subsequent "backups" need not consider the files copied previously. Of course, if they are modified again, their modification date will then be newer than this updated timestamp and they will be overwritten again.
When you are merging two sets of files on a single system, you may not wish to deal with floppy disks. For this reason, if there is no floppy disk on the system with a name beginning with "backup", Newer will look for a folder on the top level of the system disk whose name starts with "backup", and use that instead of a floppy disk. Thus, when you are doing large merges, you are not restricted to the limit of what will fit on a floppy disk.
Basic Operation.
There are three basic phases to the operation of Newer. First, you call up an existing command file and possibly change the options from those set the last time the command file was used. (You can also create a new command file by double-clicking on the application and selecting "new" from the File menu and possibly changing the default options found in a new file). Then you start the actual copy process. During the copy process, a status window keeps you informed which folders are being scanned and what files are being copied. When the copies are finished, you are presented with a log window showing what files have been copied. You may inspect and/or change this log before closing the window. You may then exit the program or open another command file (or create a new one) and start over.
There are three basic copy modes: backup, restore and merge. In "backup" mode, files are copied from the command folder to the floppy disk. In "restore" and "merge" modes, files are copied from the floppy disk to the command folder. In "backup" and "restore" mode, files are copied which are newer than the timestamp and newer than the corresponding file on the destination disk. In "merge" mode, files are copied if they are newer than the timestamp and the corresponding destination file and if the destination file is not also newer than the timestamp. Merge mode will be explained in further detail below.
Options.
When you start up Newer from a command file or create a new command file, you will see a standard Mac dialog box which shows the current settings of the options. See Figure 1. You can make any appropriate changes before proceeding.
Figure 1
Following is a brief explanation of the options. Some of the more obscure options have been deferred to sections later in the documentation to avoid overwhelming you right at the start.
Backup, Restore and Merge: these radio buttons select the mode as described above. The default mode is Backup.
Timestamp Current Value: This tells you what date and time is to be used for the timestamp.
Use Command File Date: This radio button specifies that the last modification date of the command file itself is to be used for the timestamp. Note that the last time the command file was modified was probably the last time you ran Newer with this command file. This option thus enables you to back up files changed since the last time you ran a backup. This is the default setting for the timestamp.
Use File Date: If you click on this radio button, you will be asked to select a file whose modification date will be used for the timestamp. This file should be in the same folder as the command file.
Use This Date: This radio button specifies that the date typed in the box to the right of it should be used for the timestamp. The format of the typed date should be mm/dd/yy hh:mm:ss. The two digit year is taken to be between the years 1940 and 2039. The time is optional. If the time is omitted, midnight of the date specified will be used, ie: any file modified on that day or any later day will be copied (if it meets other selection criteria). The date you type will be displayed above as the "Timestamp Current Value" if it is valid. If you type an invalid date, the date displayed will be Jan 1, 1904.
Use Previous Timestamp: This radio button allows you to run a backup with the timestamp used in a previous run. This would be particularly useful when you are using the modified date of the command file itself as the timestamp and a previous run had to be aborted, perhaps because of a full disk or because you realized that you started it with the wrong options. By using "Use Previous Timestamp", you can correct whatever problem terminated the first attempt and re-run the backup using the correct timestamp even though the command file may have been modified by the first run.
Copy Files: This option is normally checked. It indicates that you do, in fact, want to copy the files which need to be updated. If you turn off this option, you will simply get a list of the files that would be copied.
Write Log File: This option is normally checked. It indicates that you would like to have a text log which lists the copied files kept in the command file.
Copy Log File Too: This option is relevant only in backup mode. It indicates that you would like the command/log file copied to the backup disk after the log is complete. It will be copied regardless of whether it may have been bypassed during the original copy process.
Alt Prefix: This is a text string which is relevant to merge mode only. See the section on Merge for more details.
Base Folder: This is a text string which is relevant mainly to merge mode and to a lesser extent to backup mode. See the section on Merge and the section "Base Folder in Backup mode" for more details.
Disk Name and Must Match: If you type a name in the "Disk Name" field, that name is used for a backup disk name rather than "backup". If "Must Match" is checked, the name must match exactly. If "Must Match" is not checked, the first disk whose name starts with the string in "Disk Name" is used for the backup.
Subfolder Name:This text string allows backup data to be stored in a subfolder of the backup disk. For example, if you have a server volume named "Dept Server" mounted and your backup folder on that disk is name "Fred's Backup Folder", you would enter "Dept Server" in the Disk Name field and check "Must Match". You would then enter "Fred's Backup Folder" in the "Subfolder Name" field. Your backups will then go into your backup folder as though it were individually mounted on the network.
The following four "lists" can inhibit certain files or folders from being copied. Clicking on any of the list buttons brings up a dialog box which enables you to look at or edit the specified list as described below in the section "Modifying or Inspecting the Lists". The diamond to the left of the list title indicates whether there are any items in the list. An empty diamond indicates an empty list. A filled diamond indicates a list containing at least one item.
Top Level Folders: This is a list of sub-folders of the command folder to be either included or excluded from consideration for copying. By default, all files and folders in the command folder are considered. If this list is to be included, only the folders named in the list will be searched. Conversely, if this list is to be excluded, all folders not named in the list will be searched.
Include Top Level Files: This is a list of individual files in the command folder which should be included in the files considered for copying when the top level folder list is an "include" list. If the top level folder list is empty, or if it is an "exclude" list, the individual files in the command folder are automatically considered for copying and need not be specifically listed.
Exclude Files: This is a list of file names which should not be copied. Files whose names match entries in this list will not be copied no matter where in the folder substructure they may appear. Note: Newer will never copy files named "DeskTop", "deskTop", "desktop", etc whether or not there is a "desktop" entry in the "Exclude Files" list. This avoids clobbering the invisible control file by which the Mac system keeps track of your folders and files. Tops (and possibly other network systems) may create one of these files in any folder which may get mounted on the network. If there are other files of this type in your particular configuration, you should enter them in this list.
Exclude File Types: This is a list of file types which should not be copied. Files whose four letter file type match entries in this list will not be copied no matter where in the folder substructure they may appear.
Save Options Now: Clicking on Save Options Now indicates that you wish the current options settings saved to the command file immediately. Normally they are saved after you have run the copy process and close the log. This feature allows you to change the options, save them and exit without actually running a copy.
Cancel: Clicking on Cancel indicates that you do not wish to process this command file. The options dialog box will go away and you can then open another command file, create a new one, or exit back to the finder. These are accomplished respectively by "Open", "New" and "Quit" from the File menu.
Do It: Clicking on "Do It" signifies that you are satisfied with the settings of the options and wish to proceed with the copy. The options dialog box will go away and the copy process will begin.
Note: If you hold down the shift key while the program is starting, the options dialog box will be bypassed and the program will process the command file using the option settings recorded in the file on the disk. This is just as if you had let the dialog box come up and clicked on "Do It".
The Status Window.
While the program processes your request, it will display its status on the screen in a progress window (see Figure 2). The title of the program and the version you are running are displayed on the first line. The second line shows the date and time being used as the timestamp. Only files newer than this time are being considered for copying. The "Current Folder" field displays, as it says, the folder currently being processed. The "Checking" field shows the name of the file currently under consideration. The modification date and time of the file being considered are displayed to the right of the "Checking" field. When a file is being copied, the next field will say "Backing up", "Restoring", or "Merging" and will give the full file name with the folder names prepended. If you are in Merge mode and have specified an alternate prefix to be used and conditions dictate that the prefix should be used, the next field will show the name of the file being created.
Figure 2
Below the name fields, the sizes of the data and resource forks of the file being copied are displayed. A graphic indication of the progress of the copy is also shown. When copying small files on a fairly responsive network, this information will probably change too fast for you to read. It will be more informative for large files or when copying to floppies. Note that many files have only a data fork or a resource fork but not both. In these cases you will see only one progress bar. Below the size fields and progress bars the next field shows the amount of free disk space on the disk on which the files are being copied.
Below the free space field is an "error" field which will contain the text or an error number of the last error encountered. Normally, the program proceeds with the next file to copy when an error occurs. Two exceptions to this are "disk full" and "destination disk is write protected". Further copying is abandoned in these cases since it is pointless or ill-advised to continue. The error field will normally be blank when there are no errors.
Below the error field are an "OK" button and a "Cancel" button. You may cancel the copy process at any time by clicking on the cancel button (or by typing cmd-period). Normally, if all files are copied without error, the progress window is removed and you will see the list of files copied. If, however, any errors occurred, the progress window remains on your screen until you confirm that you have seen the error message(s) by clicking on "OK". Note that the errors will also appear in the log of files copied.
The Copy Log.
When the copies are complete, the list of files copied is left on your screen. See Figure 3. This is a cumulative list containing the results of each execution of the command file, along with the date of the copy and the name of the floppy disk copied to or from. The results of the copy just completed will be at the end of the list. You can edit this list using the usual Mac text editing techniques or simply look at it to make sure that the files you expected to be copied are on the list. If the program tried to copy a file and had problems, an error message will be included on the line containing the file name. If the program renamed the file while copying, as described below, this too will be noted.
Backing up to "Backup test" - 01/18/1989 04:55:56
:Newer ƒ:Newer.c
:Newer ƒ:Newer.rsrc
:Newer ƒ:process.c
:Newer ƒ:scandir.c
Backing up to "Backup test" - 01/22/1989 21:44:27
:Library ƒ:TEbuffhandler.c
:Library ƒ:windows.c
:Newer ƒ:cmdhandler.c
:Newer ƒ:file.c
:Newer ƒ:Newer.c
:Newer ƒ:Newer.rsrc
:Newer ƒ:Newer.rsrc.text
:Newer ƒ:Bad File - Error -36
:Newer ƒ:process.c
Figure 3
When you are finished editing and/or inspecting the copy log, you can close the log by selecting "Close" from the file menu, by typing cmd-W or by clicking on the "go away" box in the upper left corner of the window. If Newer added anything to the log or if you made changes to your options settings which you have not yet saved, you will get a standard Mac dialog box asking if you want to save your changes. Note that "changes" here means whatever changes you made to the options used to run the program, the program's entry of the names of copied files and your optional edits. If you choose "Discard", you will discard anything the program has added to the log and any edits you have made to the log. Then, if you made any changes to the options which have not already been saved, you will get a second dialog box asking if you wish to save the changed options. The options settings and the log text are kept in the same file: the options in the resource fork and the log text in the data fork. The text in the data fork looks like any other Macintosh text file and can thus be opened, edited, printed, etc by any word processor or any other program or desk accessory which can open 'TEXT' files.
When the log window is removed from the screen, Newer redisplays its "about" box. You can then open another command file, create a new one, or exit to the finder. These are accomplished respectively by "Open", "New" and "Quit" from the File menu.
Modifying or Inspecting the "Lists".
When you click on any of the "list" buttons in the options dialog box, a dialog box similar to the following appears:
The name of the list is shown, along with the currently selected list entry and some action buttons. The "Include" and "Exclude" radio buttons appear only for the Top Level Folder list, and are used to select whether this list is a list of sub-folders of the command folder to include in the copy process or a list of sub-folders to skip. If the list has no entries the string "*** Empty ***" will appear instead of a currently selected entry.
Clicking and holding on the selected entry will cause a pop-up menu to appear which will show you the entire list:
If the list is too long to fit on your screen it will have arrows at the top or bottom and you can pull your cursor down or up to cause the list to scroll. You can drag down to one of the other entries in the list and lift the mouse, and the item the mouse was on will become the selected item:
The "selected" item is significant only for the purpose of deleting items. You click on the "Delete Item" button to delete the selected item from the list:
You will be asked to confirm that this is your intention:
Clicking on "Delete" will delete the item, clicking on "Cancel" will cancel this operation.
You can type in a new entry by clicking on "Type a new entry":
You will then be offered a window with a field to type in and an "OK" and "Cancel" button:
The text may say "Enter new file name" or "Enter new file type" rather than "Enter new folder name" as appropriate to the list you are modifying. You type the name in the field provided and click on "OK" to enter it in the list. "Cancel" will cancel the operation.
You can select a new list entry using the Macintosh file system by clicking on "Select a new entry":
You will be offered a standard Macintosh "Get File" dialog box:
If you are modifying a file list, all files and all folders in the current folder will be included in the scrollable file/folder window in the dialog box. If you are modifying a folder list, only folders will be included. You click on a file or folder name, as appropriate, and click on "Select" to add the file or folder to the list. "Cancel" will cancel the operation. When you are modifying file lists, double-clicking on a file name will act as a "Select". When you are modifying a file or folder list, double-clicking on a folder name will descend into that folder. Note that even though you may select specific files or folders for the lists, folders are included or excluded from the command level folder only. This inclusion or exclusion is done simply by comparing the sub-folder names to the names in the list. Likewise, any file name in the file exclude list will cause all files of that name to be skipped no matter where in the folder substructure they may appear. When you select files for the file type exclude list, the type of the file selected is placed in the list and any file of that type will be skipped, no matter where in the folder substructure it may appear.
When you add an item to a list, either by typing it in or by selecting it, it is added to the end of the list and becomes the selected item.
Merge Mode.
Merge mode is useful when you and someone else (or you operating on different machines or different disks) have made parallel modifications to separate copies of the same set of files and you must create a "merged" set containing both sets of changes. For example, the timestamp may represent the date/time that you made a copy of a master version of a set of files. If you use Newer in "backup" mode to create a floppy or folder containing your changes and then use "restore" mode to integrate those files into the "master" folder, you may overwrite files which someone else has delivered since you made your copy. If you use "merge" mode rather than "restore" mode to integrate, and Newer finds that the master copy of a file you have changed is newer than the timestamp, it assumes that someone else has made a change which you should not overwrite. As noted below in the discussion of "alt prefix", either the copy will not be made and an error message will be placed in the log file, or the copy will be made but the resulting file in the master folder will have a different name.
Alt Prefix: You can use this text string to copy files which are newer than the timestamp but for which the destination file is also newer than the timestamp. If no "alt prefix" string is specified, these files will not be copied but will be listed in the log with the error message "Timestamp problem". If an "alt prefix" string is specified, the files will be copied but the name of the copy will be the name of the original file with the "alt prefix" string prepended. If, for example, the file is named "sample file" and the "alt prefix" is "gt_", the resulting copy will be named "gt_sample file". Note that the "alt prefix" is used only when the file in the master folder which would be overwritten has been modified since the timestamp. Files which have not been modified since the timestamp will be overwritten without changing their name just as they would be in "restore" mode.
Base Folder: In some cases, a simple date comparison between your file and a file in the folder with which you are merging is not sufficient. For example, if another person has been working on a project over several days or weeks, she may deliver a file which was modified on her disk prior to the copy of the master which you made, even though the delivery itself takes place after your timestamp. To guard against this, if you have a complete copy of the master folder at the time you started your changes, you can specify a "Base Folder" in merge mode and a copy of your files will be inhibited if the modification date and time of the file in the master folder differs from that of the file of the same name in the "base" folder, no matter what the actual dates are. The notation for this text string is the internal Macintosh folder notation which uses a colon to separate folder and file names. The base folder is specified relative to the command folder. A double colon is used to indicate the parent folder. Thus if, as would typically be the case, the base folder is a "sibling" of the working folder and named "Base Folder", the Base Folder string would be "::Base Folder".
Merge Procedure.
The recommended working procedure for using Newer to do a merge is to start your work by making a complete copy of the master folder to which you will be making changes. Before actually making changes, make an additional copy and name it "Base Folder". Create, in your working folder, a file whose modification time can be used later for a timestamp. (or modify a pre-existing file kept for this purpose). Now make your changes in your working folder. When you are ready to integrate and you think that someone else may have made changes to the master folder since you made your copy, create an empty folder named "Backup Folder" on your system disk. Now run Newer in "backup" mode from your working folder and use the timestamp file you created or modified when you made your copy. This will copy to the backup folder all the files you modified or created since you made the copy of the master folder. If you have created test files you may want to set up the "exclude file name" list and the "exclude file type" list to avoid copying these files. You may want to look at the log of files copied to be sure that all the files in the backup folder are files which should be delivered. If any unwanted files have been copied, you can remove them from the backup folder with the finder before doing the actual merge. Now run Newer in "merge" mode from a command file in the master folder and specify Base Folder to be "::Base Folder" and use a timestamp of 1/1/80 (since you want to copy all the files in "Backup Folder"). Specify an "alt prefix" string consisting of your initials or some short string. When the copy is complete, you can see from the log which files were delivered successfully and which files had to be renamed with your alternate prefix. These latter files will have to be integrated manually.
Base Folder in Backup Mode:
The base folder has a function in backup mode which is similar to its function in merge mode. If you specify a base folder in backup mode, files are copied which are newer than the timestamp, newer than a possible pre-existing copy on the backup disk and have a modified date which is different (not necessarily newer!) than the same file in the base folder. This would enable you to do "incremental" backups of a folder or disk which may have files copied onto it whose modified dates predate the last backup performed and which would thus not be copied by a normal incremental backup. It is, of course, somewhat expensive since it requires an extra copy of the data.
Site license terms:
For a single registration (ie: one entry in my data base), for a number of Macs owned by one organization in one building or building complex:
1st licence: $25.00
2nd-10th: $12.50 each
11 or more: $150.00 total
Only one disk and copy of the documentation will be sent. The documentation is included on the disk in Word 3.0 and 'TEXT' format. You may print additional copies or xerox the copy included with the disk.
Only one notice of bugs or upgrade availability will be sent.
Credits:
Thanks to Think for inventing Lightspeed C. Thanks to Monty and Rod for lots of early advice on using and programming the Mac. Thanks to Roberta for letting me implement a few features in "Mum's the Word" to get my feet wet in Mac programming. Thanks to Media Solutions and Kodak for paying me to work on the Mac during the day and for occasional personal use of the laserwriter. Thanks to my wonderful co-workers at Kodak's Color Imaging Systems group for being beta testers. Thanks to Denise and several early users for helping with the Doc. Thanks especially to Steve Meuse of Cytyc who sent me more bug reports and suggestions than all other users combined. Many of Steve's suggestions were integrated into Newer at version 1.1b5.
Feedback:
I would like to know what you are using Newer for (backup/restore vs keeping two systems in sync vs file set merging vs things I haven't thought of yet), what features you would like added, whether you understood the documentation, and especially, bug reports.
You can write to me at the address given above for registration or send electronic mail to me by name on the BCS Mac BBS, by "Gtstone" on America OnLine or by number (72701,247) on Compuserve (when are they going to enter the eighties and let people have logon names?).
